home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / program / swagd_f.zip / FAQ.SWG / 0015_BP7 Help file format.pas < prev    next >
Pascal/Delphi Source File  |  1993-11-02  |  14KB  |  400 lines
  1. {
  2. Derek Powles <derek.powles@eng.ox.ac.uk>
  3.  
  4. Subject: Re Help File format
  5.  
  6. Expanded information on Help File sources.
  7.    In an earlier message I referred to four authors For the book in (1)
  8. below - my mistake - there are three.
  9.     Derek
  10.  
  11. (1) 'A Programmer's Guide to Turbo Vision' by Ertl, Machholz and Golgath,
  12. authored by the Pascal product management team at Borland in Germany.
  13. Pub. Addison-Wesley, ISBN 0-201-62401-X.
  14. The book contains chapter 12 ( 18 pages ) describing how to add a
  15. conText sensitive help Unit to your own TV Program.
  16. The use of TVHC is described ( 2 pages ). TVHC generates helptxt.pas and
  17. helptxt.hlp Files from a special helptxt.txt File. The .pas File is
  18. included in your main routine as a Unit. The HelpFile Unit is also needed,
  19. this Unit, TVHC and a working example are in the TVDEMO subdirectory.
  20. This .hlp File is not compatible With the Borland supplied Dos help Files,
  21. these have a name of the form *.t*h. I believe I am correct in stating that,
  22. other than demohelp.hlp, all supplied *.hlp Files are For Windows use.
  23.  
  24. (2) The 'Borland Open Architecture Handbook For Pascal' describes and
  25. supplies the Program HL.EXE. Chapter 8 tells you '...how to create, build,
  26. and maintain Borland Dos Help Files'. I have attached information gleaned
  27. from this book.
  28. There are two sections, the first is information taken from the book and
  29. the second is a Unit holding data structures.
  30.  
  31. look For the *****cut here*****.
  32.  
  33. ******************cut here*********************
  34. {  See `Borland Open Architecture Handbook For Pascal' pages 170-177 }
  35. (***************************************************************
  36. Binary help File format -
  37.  
  38. Records are grouped in four sections
  39.  
  40.  1 - File stamp
  41.  2 - File signature
  42.  3 - File version
  43.  4 - Record Headers
  44.    a - File header Record
  45.    b - conText
  46.    c - Text
  47.    d - keyWord
  48.    e - index
  49.    f - compression Record
  50.    g - indextags {= subheadings, = qualifiers}
  51.  
  52.    ***************************************************************
  53.  
  54.  1 - A File stamp is a null terminated String, note case,
  55.       `TURBO PASCAL HelpFile.\0' or
  56.       `TURBO C Help File.\0'  identifying the File in readable form.
  57.       The null Character is followed by a Dos end-of-File Charcater $1A.
  58.       This is defined as ;STAMP in the help source File.
  59.  
  60.  2 - The File signature For Borland products is a null terminated
  61.       String `$*$* &&&&$*$' (no quotes in help Files).
  62.       This is defined as ;SIGNATURE in the help source File.
  63.  
  64.  3 - The File version is a Record of two Bytes that define the version
  65.       of help format and the help File Text respectively,
  66.  
  67.       Type
  68.         TPVersionRec    = Record
  69.           Formatversion : Byte;
  70.           TextVersion   : Byte   {defined With ;VERSION}
  71.           { this is For info only }
  72.         end;
  73.       FormatVersion For BP7     = $34
  74.                         TP6     = $33
  75.                         TP5     = $04
  76.                         TP4     = $02
  77.                         TC++3.0 = $04
  78.  
  79.  4 - Record Headers -
  80.   All the remaining Records have a common format that includes a header
  81.   identifying the Record's Type and length.
  82.  
  83.     Type
  84.       TPrecHdr  = Record;
  85.         RecType   : Byte;
  86.         RecLength : Word;
  87.       end;
  88.  
  89.   Field RecType is a code that identifies the Record Type.
  90.     Type
  91.       RecType =
  92.         (RT_FileHeader,    {0}
  93.          RT_ConText,       {1}
  94.          RT_Text,          {2}
  95.          RT_KeyWord,       {3}
  96.          RT_Index,         {4}
  97.          RT_Compression);  {5}
  98.          RT_IndexTags,     {6 - only in FormatVersion $34}
  99.  
  100.   Field RecLength gives the length of the contents of the Record in
  101.   Bytes, not including the Record header. The contents begin With the
  102.   first Byte following the header.
  103.  
  104.   The field `RecType' Types are explained in the following Text.
  105.  
  106.   Although this structure allows an arbitrary order of Records, existing
  107.   Borland products assume a fixed Record ordering as follows:-
  108.         File header Record
  109.         compression Record
  110.         conText table
  111.         index table
  112.         indextags Record {introduced in BP7}
  113.         Text Record
  114.         keyWord Record
  115.  
  116.  4.a The File header Record defines Various parameters and options
  117.   common to the help File.
  118.  
  119.   Type
  120.     TPFileHdrRec     = Record
  121.       Options        : Word;
  122.       MainIndexScreen: Word;
  123.       Maxscreen size : Word;
  124.       Height         : Byte;
  125.       Width          : Byte;
  126.       LeftMargin     : Byte;
  127.     end;
  128.  
  129.       Options - is a bitmapped field. Only one option currently
  130.                 supported.
  131.                 OF_CaseSense ($0004) (C only, not Pascal)
  132.                   if set, index tokens are listed in mixed case
  133.                   in the Index Record, and index searches will
  134.                   be Case sensitive.
  135.                   if cleared, index tokens are all uppercase in
  136.                   the Index Record, and index searches will ignore
  137.                   case.
  138.                   Defined With ;CASESENSE.
  139.  
  140.       MainIndexScreen - this is the number assigned to the conText
  141.                   designated by the ;MAININDEX command in the help
  142.                   source File.
  143.                   if ;MAININDEX is not used, MainIndexScreen is set
  144.                   to zero.
  145.  
  146.       MaxScreenSize - this is the number of Bytes in the longest Text
  147.                   Record in the File (not including the header). This
  148.                   field is not currently in use.
  149.  
  150.       Height, Width - This is the default size in rows and columns,
  151.                   respectively, of the display area of a help Window.
  152.                   Defined With ;HEIGHT and ;WIDTH.
  153.  
  154.       LeftMargin - Specifies the number of columns to leave blank on
  155.                   the left edge of all rows of help Text displayed.
  156.                   Defined With ;LEFTMARGIN.
  157.  
  158.  4.b ConText table -
  159.   This is a table of Absolute File offsets that relates Help conTexts to their
  160.   associated Text. The first Word of the Record gives the number of conTexts
  161.   in the table.
  162.   The remainder of the Record is a table of n ( n given by first Word) 3-Byte
  163.   Integers (LSByte first). The table is indexed by conText number (0 to n-1).
  164.   The 3-Byte Integer at a given index is an Absolute Byte that is offset in
  165.   the Help File where the Text of the associated conText begins.
  166.   The 3-Byte Integer is signed (2's complement).
  167.   Two special values are defined -
  168.         -1 use Index Screen Text (defined in File Header Record).
  169.         -2 no help available For this conText.
  170.   ConText table entry 0 is not used.
  171.  
  172.  4.c Text descriptions -
  173.   The Text Record defines the compressed Text of conText.
  174.   Text Records and keyWords appear in pairs, With one pair For each
  175.   conText in the File. The Text Record always precedes its associated
  176.   keyWord. Text Records are addressed through the File offset values
  177.   found in the conText table described above.
  178.  
  179.   The RecLength field of the Text Record header defines the number
  180.   of Bytes of compressed Text in the Record.
  181.   The Compression Record defines how the Text is compressed.
  182.   if the Text is nibble encoded, and the last nibble of the last Byte
  183.   is not used, it is set to 0.
  184.   Lines of Text comprising the the Text Record are stored as null
  185.   terminated Strings.
  186.  
  187.  4.d the keyWord Record defines keyWords embedded in the preceeding Text
  188.   Record, and identifies related Text Records.
  189.   The Record begins With the following fixed fields:
  190.     UpConText   : Word;
  191.     DownConText : Word;
  192.     KeyWordCnt  : Word;
  193.  
  194.   UpConText and DownConText give the conText numbers of the previous
  195.   and next sections of Text in a sequence, either may be zero,
  196.   indicating the end of the conText chain.
  197.  
  198.   KeyWordCnt gives the number of keyWords encoded in the associated
  199.   Text Record.
  200.   Immediately following this field is an Array of KeyWord Descriptor
  201.   Records of the following form:
  202.     Type
  203.       TPKwDesc = Record;
  204.         KwConText: Word;
  205.       end;
  206.  
  207.   The keyWords in a Text Record are numbered from 1 to KeyWordCnt in the
  208.   order they appear in the Text (reading left to right, top to bottom).
  209.  
  210.   KwConText is a conText number (index into the conText table) indicating
  211.   which conText to switch to if this keyWord is selected by the user.
  212.  
  213.  4.e Index table -
  214.   This is a list of index descriptors.
  215.   An index is a token (normally a Word or name) that has been explicitly
  216.   associated With a conText using the ;INDEX command in the source Text File.
  217.   More than one index may be associated With a conText, but any given index
  218.   can not be associated With more than one conText.
  219.   The list of index descriptors in the Index Record allows the Text of an
  220.   index token to be mapped into its associated conText number.
  221.  
  222.   The first Word of the Record gives the number of indexes defined in the
  223.   Record.
  224.   The remaining Bytes of the Record are grouped into index descriptors.
  225.   The descriptors are listed in ascending order based on the Text of the index
  226.   token (normal ascii collating sequence). if the OF_CaseSense flag is not set
  227.   in the option field of the File header Record, all indexes are in uppercase
  228.   only.
  229.  
  230.   Each index descriptor Uses the following format:
  231.     LengthCode    : Byte;
  232.     UniqueChars   : Array of Byte;
  233.     ConTextNumber : Word;
  234.  
  235.   The bits of LengthCode are divided into two bit fields.
  236.   Bits(7..5) specify the number of Characters to carry over from the start of
  237.   the previous index token String.
  238.   Bits(4..0) specify the number of unique Characters to add to the end of the
  239.   inherited Characters.
  240.  
  241.   Field UniqueChars gives the number of unique Characters to add.
  242.   e.g. if the previous index token is `addition', and the next index token is
  243.   `advanced', we inherit two Characters from the previous token (ad), and add
  244.   six Characters (vanced); thus LengthCode would be $46.
  245.  
  246.   ConTextNumber gives the number of the conText associated With the index.
  247.   This number is an index into the conText table described above.
  248.  
  249.  4.f A compression Record defines how the contents of Text Records are
  250.   encoded.
  251.      Type
  252.        TPCompress = Record
  253.          CompType : Byte;
  254.          CharTable: Array[0..13] of Byte;
  255.        end;
  256.  
  257.   CompType - nibble encoding is the only compression method currently
  258.              in use.
  259.                      Const CT_Nibble = 2;
  260.   The Text is encoded as a stream of nibbles. The nibbles are stored
  261.   sequentially; the low nibble preceeds the high nibble of a Byte.
  262.   Nibble values ($0..$D) are direct indexes into the CharTable field of
  263.   the compression Record. The indexed Record is the literal Character
  264.   represented by the nibble. The Help Linker chooses the 14 (13?) most
  265.   frequent Characters For inclusion in this table. One exception is that
  266.   element 0 always maps to a Byte value of 0.
  267.  
  268.   The remaining two nibble values have special meanings:
  269.           Const
  270.             NC_RawChar = $F;
  271.             NC_RepChar = $E;
  272.  
  273.   Nibble code NC_Char introduces two additional nibbles that define a
  274.   literal Character; the least significant nibble first.
  275.  
  276.   Nibble code NC_RepChar defines a Repeated sequence of a single Character.
  277.   The next nibble gives the Repeat count less two, (counts 2 to 17 are
  278.   possible)
  279.   The next nibble(s) define the Character to Repeat; it can be either a
  280.   single nibble in the range ($0..$D) representing an index into
  281.   CharTable, or it can be represented by a three nibble NC_RawChar
  282.   sequence.
  283.  
  284.  
  285.  4.g RT_IndexTags is in FormatVersion $34 only. This provides a means
  286.   For including index sub headings in the help File.
  287.   The Record header is followed by a list of Variable length tag Records
  288.   Type
  289.     IndRecType = Record;
  290.       windexNumber: Word; {index into the RT_Index Record }
  291.       StrLen: Byte;  {length of tag String(not including terminating 0)}
  292.       szTag: Array[0..0] of Char; {disable range checking}{zero term tag
  293.                                    String}
  294.     end;
  295.    The first structure in the Array is a special entry which has the
  296.    windexnumber set to $FFFF, and contains the default ;DESCRIPTION
  297.    in Case there are duplicate index entries and no tags were specified.
  298. *)
  299.  
  300. Unit HelpGlobals;
  301. { This File contains only the structures which are found in the help Files }
  302.  
  303. Interface
  304.  
  305. Const
  306.   Signature      = '$*$* &&&&*$';   {+ null terminator }
  307.   NC_RawChar     = $F;
  308.   NC_RepChar     = $E;
  309.  
  310. Type
  311.   FileStamp      = Array [0..32] Of Char; {+ null terminator + $1A }
  312.   FileSignature  = Array [0..12] Of Char; {+ null terminator }
  313.  
  314.   TPVersion      = Record
  315.     FormatVersion : Byte;
  316.     TextVersion   : Byte;
  317.   end;
  318.  
  319.   TPRecHdr       = Record
  320.     RecType   : Byte; {TPRecType}
  321.     RecLength : Word;
  322.   end;
  323.  
  324. Const   {RecType}
  325.   RT_FileHeader  = Byte ($0);
  326.   RT_ConText     = Byte ($1);
  327.   RT_Text        = Byte ($2);
  328.   RT_KeyWord     = Byte ($3);
  329.   RT_Index       = Byte ($4);
  330.   RT_Compression = Byte ($5);
  331.   RT_IndexTags   = Byte ($6);
  332.  
  333.  
  334. Type
  335.   TPIndRecType = Record
  336.     windexNumber : Word;
  337.     StrLen       : Byte;
  338.     szTag        : Array [0..0] Of Char;
  339.     { disable range checking}
  340.   end;
  341.  
  342.   TPFileHdrRec = Record
  343.     Options         : Word;
  344.     MainIndexScreen : Word;
  345.     Maxscreensize   : Word;
  346.     Height          : Byte;
  347.     Width           : Byte;
  348.     LeftMargin      : Byte;
  349.   end;
  350.  
  351.  
  352.   TP4FileHdrRec = Record                  {derived from sample File}
  353.     Options    : Word;
  354.     Height     : Byte;
  355.     Width      : Byte;
  356.     LeftMargin : Byte;
  357.   end;
  358.  
  359.   TPCompress = Record
  360.     CompType  : Byte;
  361.     CharTable : Array [0..13] Of Byte;
  362.   end;
  363.  
  364.   TPIndexDescriptor = Record
  365.     LengthCode    : Byte;
  366.     UniqueChars   : Array [0..0] Of Byte;
  367.     ConTextNumber : Word;
  368.   end;
  369.  
  370.   TPKeyWord = Record
  371.     UpConText   : Word;
  372.     DownConText : Word;
  373.     KeyWordCnt  : Word;
  374.   end;
  375.  
  376.   TPKwDesc = Record
  377.     KwConText : Word;
  378.   end;
  379.  
  380.  
  381.   TmyStream = Object(TBufStream) end;
  382.  
  383.   PListRecHdr = ^RListRecHdr;
  384.  
  385.   RListRecHdr = Record
  386.     PNextHdr : PListRecHdr; {Pointer to next list element}
  387.     RRecType : TPRecHdr;    {RecType, RecLength}
  388.     PRecPtr  : Pointer;     {Pointer to copy of Record}
  389.   end;
  390.  
  391.   ConTextRecHd = Record
  392.     NoConTexts  : Word;
  393.     PConTextRec : Pointer;
  394.   end;
  395.  
  396.  
  397. Implementation
  398. end.
  399.  
  400.